R Markdown for Reproducible Reports

class: title-slide, center, bottom

## R Markdown for Reproducible Reports
  
.pull-left[
#### Heidi E. Steiner &#183; Data Science Institute

######  All content is [RStudio Education](https://github.com/rstudio-education/rmd4medicine), CC-BY. All art (unless otherwise noted) is by [Desirée De Leon](https://desiree.rbind.io/) and [Allison Horst](https://www.allisonhorst.com/), CC-BY-NC-ND.
]

---

.left-column[

 
 ?
 
]

.right-column[

# What is R Markdown?

1. An authoring framework for data science.

1. A document format (`.Rmd`).

1. An R package named `rmarkdown`.

1. A file format for making dynamic documents with R.

1. A tool for integrating prose, code, and results.

1. A computational document.

1. Wizardry.

]

---

.left-column[

 
 ?
 
]

.right-column[

# What is R Markdown?

1. ["An authoring framework for data science."](https://rmarkdown.rstudio.com/lesson-1.html) (✔️)

1. [A document format (`.Rmd`).](https://bookdown.org/yihui/rmarkdown/) (✔️)

1. [An R package named `rmarkdown`.](https://rmarkdown.rstudio.com/docs/) (✔️)

1. ["A file format for making dynamic documents with R."](https://rmarkdown.rstudio.com/articles_intro.html) (✔️)

1. ["A tool for integrating text, code, and results."](https://r4ds.had.co.nz/communicate-intro.html) (✔️)

1. ["A computational document."](http://radar.oreilly.com/2011/07/wolframs-computational-documen.html) (✔️)

1. Wizardry. (🧙‍♀️)

]

---

.left-column[

 
 ?
 
]

.right-column[

# How does R Markdown work?

1. 🤷

1. I press knit, a document appears, and I believe that anything happening in between could be actual magic.

1. `knitr` executes the code and converts `.Rmd` to `.md`; **Pandoc** renders the `.md` file to the output format you want.

]

---
background-image: url(data:image/png;base64,#images/rmd_flowchart.png)

# How *does* R Markdown work?

???

1. 🤷 (✔️)

1. ["I press knit, a document appears, and I believe that anything happening in between could be actual magic."](https://twitter.com/allison_horst/status/1070323369600442368?s=20) (🧙‍♂️)

1. `knitr` executes the code and converts `.Rmd` to `.md`; **Pandoc** renders the `.md` file to the output format you want. (✔️)

---
class: middle, center

# Change your mental model

.pull-left1[

### Source &harr; output

]

.pull-right1[

### Source &rarr; output

]

---
class: middle, center

# Change your mental model

.pull-left1[

### Source &harr; output

]

.pull-right1[

### Source &rarr; output

]

---
background-image: url(data:image/png;base64,#images/welliewishers/Slide2.png)
background-size: cover
class: top, center

.footnote[https://www.americangirl.com/shop/c/welliewishers]

---
class: middle, inverse, center

# Same ~~doll~~ source

# Different occasions

---
class: your-turn

# First look

Explore `01-explore.Rmd`. 
Look at the source, then 🧶 **Knit** to HTML.

Try to identify these parts in the source and the output:

1. The **metadata**

1. The **text**

1. The **code**

1. The **output**

**If this was easy**, try to identify global chunk options!

---
class: center, middle

---
class: middle, center, inverse

1

# Metadata

---

# metadata: YAML

.pull-left1[

_"YAML Ain't Markup Language"_

```yaml
---
key: value
---
```

]

.pull-right1[

]

---

# Save output options in your YAML

.pull-left1[

```yaml
---
output: html_document
---
```

```yaml
---
output:
  html_document:
    toc: true
---
```

]

.pull-right1[

]

---
class: your-turn

# Your turn

## Edit your YAML

Use **`?html_document`** from your R console to:

1. Add a floating table of contents

1. Add a theme

1. Use the "kable" method to print data frames (more on this later!)

🧶 **Knit** to HTML to see the output.

**If this was easy**, try to embed the `Rmd` source code to download.

_psst...answers on the next slide..._

---
class: your-turn

# Answers

```yaml
---
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    df_print: kable
    code_download: true
---
```
---

# What is hard about YAML?

.pull-left1[
+ Indentations matter

+ Rarely informative error messages

+ Knowing which output options are relevant for different formats (i.e., Word, PDF, HTML, etc.)

+ Easy to forget the right `key`

+ Easy to forget the possible `values` for a given `key`
]

---
class: inverse, center, middle

2

# Markdown Text

---
name: 03-formative
class: middle

# Pop quiz

.pull-left1[

How do you add lists in Markdown? Bulleted? Numbered?

`! Item 1`

`- Item 1`

`# Item 1`

`1. Item 1`

]

.pull-right1[

<img src="data:image/png;base64,#images/markdown.png" width="95%" style="display: block; margin: auto auto auto 0;" />
https://commonmark.org/help/tutorial/
]

---
class: inverse, center, middle

3

# code

---

# Code chunks

.pull-left1[

````
```{r}
mockdata %>% 
  distinct(status)
```
````

What is the fate of this chunk?

]

.pull-right1[

```r
mockdata %>% 
  distinct(status)
#>   status
#> 1      2
#> 3      1
```

]

---

# Code chunks

.pull-left1[

````
```{r}
n_sites <- n_distinct(mockdata$inst)
```
````

What fate do you predict here?

]

.pull-right1[

```r
n_sites <- n_distinct(mockdata$inst)
```

]

---

# Code chunks

.pull-left1[

````
```{r}
n_sites <- n_distinct(mockdata$inst)
n_sites
```
````

]

.pull-right1[

```r
n_sites <- n_distinct(mockdata$inst)
n_sites
#> [1] 19
```

]

---

# Code chunks

.pull-left1[

````
```{r}
ggplot(mockdata, aes(x = status, 
                     fill = status)) +
  geom_bar()
```
````

What about this one?

]

.pull-right1[

```r
ggplot(mockdata, aes(x = status, 
                     fill = status)) +
  geom_bar()
```

]

---

# Add chunks

button or

Command (or Cmd) `⌘` + Option (or Alt) `⌥` +  `i` (Mac)

Ctrl + Alt + `i` (Windows/Linux)

# Run chunks

interactively (show button)

whole doc (knit button or run all chunks)

---
class: inverse, center, middle

4

# Output

---

# Chunk options

.pull-left1[

````
```{r}
glimpse(mockdata)
```
````

]

.pull-right1[

```r
glimpse(mockdata)
#> Rows: 228
#> Columns: 10
#> $ inst <fct> 3, 3, 3, 5, 1, 12, 7, 11, 1, 7, 6, 16, 11, 21, 12, 1, 22, 16…
#> $ time <dbl> 306, 455, 1010, 210, 883, 1022, 310, 361, 218, 166, 170, 654…
#> $ status <fct> 2, 2, 1, 2, 2, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, …
#> $ age <dbl> 74, 68, 56, 57, 60, 74, 68, 71, 53, 61, 57, 68, 68, 60, 57, …
#> $ sex <fct> 1, 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 2, 2, 1, 1, 1, 1, 1, 2, 1, …
#> $ ph.ecog <fct> 1, 0, 0, 1, 0, 1, 2, 2, 1, 2, 1, 2, 1, NA, 1, 1, 1, 2, 2, 1,…
#> $ ph.karno <dbl> 90, 90, 90, 90, 100, 50, 70, 60, 70, 70, 80, 70, 90, 60, 80,…
#> $ pat.karno <dbl> 100, 90, 90, 60, 90, 80, 60, 80, 80, 70, 80, 70, 90, 70, 70,…
#> $ meal.cal <dbl> 1175, 1225, NA, 1150, NA, 513, 384, 538, 825, 271, 1025, NA,…
#> $ wt.loss <dbl> NA, 15, 15, 11, 0, 0, 10, 1, 16, 34, 27, 23, 5, 32, 60, 15, …
```

]

---

# echo

.pull-left1[

````
```{r echo=FALSE}
glimpse(mockdata)
```
````

]

.pull-right1[

```
#> Rows: 228
#> Columns: 10
#> $ inst <fct> 3, 3, 3, 5, 1, 12, 7, 11, 1, 7, 6, 16, 11, 21, 12, 1, 22, 16…
#> $ time <dbl> 306, 455, 1010, 210, 883, 1022, 310, 361, 218, 166, 170, 654…
#> $ status <fct> 2, 2, 1, 2, 2, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, …
#> $ age <dbl> 74, 68, 56, 57, 60, 74, 68, 71, 53, 61, 57, 68, 68, 60, 57, …
#> $ sex <fct> 1, 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 2, 2, 1, 1, 1, 1, 1, 2, 1, …
#> $ ph.ecog <fct> 1, 0, 0, 1, 0, 1, 2, 2, 1, 2, 1, 2, 1, NA, 1, 1, 1, 2, 2, 1,…
#> $ ph.karno <dbl> 90, 90, 90, 90, 100, 50, 70, 60, 70, 70, 80, 70, 90, 60, 80,…
#> $ pat.karno <dbl> 100, 90, 90, 60, 90, 80, 60, 80, 80, 70, 80, 70, 90, 70, 70,…
#> $ meal.cal <dbl> 1175, 1225, NA, 1150, NA, 513, 384, 538, 825, 271, 1025, NA,…
#> $ wt.loss <dbl> NA, 15, 15, 11, 0, 0, 10, 1, 16, 34, 27, 23, 5, 32, 60, 15, …
```

]

---

# eval

.pull-left1[

````
```{r eval=FALSE}
glimpse(mockdata)
```
````

]

.pull-right1[

```r
glimpse(mockdata)
```

]

---

# include

.pull-left1[

````
```{r include=FALSE}
glimpse(mockdata)
```
````

]

.pull-right1[

]

---

# Chunk options

.pull-left1[

````
```{r echo=TRUE, results='hide'}
glimpse(mockdata)
```
````
+ Place between curly braces `{r option=value}`

+ Multiple options separated by commas `{r option1=value, option2=value}`

+ Careful! The `r` part is the **code engine** (other engines possible)
]

.pull-right1[

```r
glimpse(mockdata)
```

]

---
class: center
background-image: url(data:image/png;base64,#https://pbs.twimg.com/media/EXm5IN8UwAADiRQ?format=jpg&name=4096x4096)
background-size: cover

.pull-right1[

### Use other code engines!

]

---

.left-column[
# Default options
]

.right-column[

```r
str(knitr::opts_chunk$get())
#> List of 53
#>  $ eval         : logi TRUE
#>  $ echo         : logi TRUE
#>  $ results      : chr "markup"
#>  $ tidy         : logi FALSE
#>  $ tidy.opts    : NULL
#>  $ collapse     : logi TRUE
#>  $ prompt       : logi FALSE
#>  $ comment      : chr "#>"
#>  $ highlight    : logi TRUE
#>  $ size         : chr "normalsize"
#>  $ background   : chr "#F7F7F7"
#>  $ strip.white  : 'AsIs' logi TRUE
#>  $ cache        : logi FALSE
#>  $ cache.path   : chr "00-rmd_cache/html/"
#>  $ cache.vars   : NULL
#>  $ cache.lazy   : logi TRUE
#>  $ dependson    : NULL
#>  $ autodep      : logi FALSE
#>  $ cache.rebuild: logi FALSE
#>  $ fig.keep     : chr "high"
#>  $ fig.show     : chr "asis"
#>  $ fig.align    : chr "default"
#>  $ fig.path     : chr "00-rmd_files/figure-html/"
#>  $ dev          : chr "png"
#>  $ dev.args     : NULL
#>  $ dpi          : num 72
#>  $ fig.ext      : NULL
#>  $ fig.width    : num 7
#>  $ fig.height   : num 7
#>  $ fig.env      : chr "figure"
#>  $ fig.cap      : NULL
#>  $ fig.scap     : NULL
#>  $ fig.lp       : chr "fig:"
#>  $ fig.subcap   : NULL
#>  $ fig.pos      : chr ""
#>  $ out.width    : NULL
#>  $ out.height   : NULL
#>  $ out.extra    : NULL
#>  $ fig.retina   : num 1
#>  $ external     : logi TRUE
#>  $ sanitize     : logi FALSE
#>  $ interval     : num 1
#>  $ aniopts      : chr "controls,loop"
#>  $ warning      : logi TRUE
#>  $ error        : logi FALSE
#>  $ message      : logi TRUE
#>  $ render       : NULL
#>  $ ref.label    : NULL
#>  $ child        : NULL
#>  $ engine       : chr "R"
#>  $ split        : logi FALSE
#>  $ include      : logi TRUE
#>  $ purl         : logi TRUE
```

]

---

# Chunk labels

.pull-left1[

````
```{r peek, echo=FALSE, results='hide'}
glimpse(mockdata)
```
````
+ Place between curly braces `{r label}`

+ Separated options with commas `{r label, option1=value}`

+ Careful! No duplicate chunk labels

]

.pull-right1[

````
    ```{r peek}
    head(mockdata)
    ```
    ````

```
 Error in parse_block(g[-1], g[1], params.src) : 
 duplicate label 'peek'
 Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
 Execution halted
 ```

]

---
class: middle, center

# A good chunk label

.pull-left[

### Good

`myplot`

`my-plot`

`myPlot`

`myplot1`

]

.pull-right[

### Bad

`my_plot`

`my plot`

everything else!

]

---
background-image: url(data:image/png;base64,#images/pour.jpeg)
background-position: left
background-size: contain
class: middle, center

.pull-right[
![](data:image/png;base64,#images/figs-label.png)
]

---

# The setup chunk

.pull-left1[

````
```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,   
  comment = "#>", 
  out.width = "100%" 
)
```
````

]

.pull-right1[

+ A special chunk label: `setup`

+ Typically the first chunk

+ All following chunks will use these options (i.e., sets global chunk options)

+ **Tip**: set `include=FALSE`

+ You can (and should) use individual chunk options too

]

---
class: your-turn

# Your turn

## New data dump! 📰

Data from more sites just came in &mdash; we now have data for 18 study sites and need to update our report.

1. Replace `2022-01-01_lungdat.csv` with `2022-02-22_lungdat.csv` in the file `01-explore.Rmd`.

1. 🧶 **Knit** to HTML. Do you see data for all sites?

**If this was easy**, try outputting to Microsoft Word Document format!

---
class: middle, center

https://rmarkdown.rstudio.com/docs/reference/index.html#section-output-formats

---
class: middle, center, inverse

!

# Extension Packages

---
background-image: url(data:image/png;base64,#images/bookdown.png)
background-size: 10%
background-position: 42% 2%

## Bookdown
.pull-left1[
While writing single reports is quite common, so is also writing book-style reports.  
Book-style reports include chapters, table of contents, appendices etc.    
These are not arbitrary to compile and set up.

Bookdown to the rescue. 
Create lovely books in html, pdf, or even e-book format!

- Yihui Xie's - [Bookdown book on bookdown](https://bookdown.org/yihui/bookdown/)  
]

.pull-right1[
<img src="data:image/png;base64,#images/bookdown_ex.png" width="100%" />
]

---
background-image: url(data:image/png;base64,#images/pagedown.png)
background-size: 10%
background-position: 42% 2%

## Pagedown

.pull-left1[
html documents usually are a single page, that can be scrolled for ever and ever an ever.  
Some times, you'd like to have pages also in html, without needing to do pdf or create an  
entire bookdown book.

Pagedown helps you do this, making really sleek paginated html reports.

Pagedown also has templates for html resumes, business cards and more!

- Yihui Xie's - [Paginated html report of paginated html reports](https://pagedown.rbind.io/)  
]

.pull-right1[
<img src="data:image/png;base64,#images/pagedown_ex.png" width="1435" height="100%" />
]

---
background-image: url(data:image/png;base64,#images/posterdown.png)
background-size: 10%
background-position: 42% 2%

## Posterdown
.pull-left1[
Posterdown is great for making... posters!
The package is very simple to use if you know rmarkdown already,
and has some nice tempaltes to build on.

- Brent Thorne's - [Poster of posterdown](https://brentthorne.github.io/posterdown_html_showcase/)

]

.pull-right1[
<img src="data:image/png;base64,#images/poster_ex.png" width="100%" />
]

---
background-image: url(data:image/png;base64,#images/blogdown.png)
background-size: 10%
background-position: 42% 2%

## Blogdown

.pull-left1[

Blogging can be a fun way to disseminate research, data and coding.  
It's a great way to show-case your skills and tell others about the cool things you are learning and figuring out.

- Yihui Xie's - [Blogdown book](https://bookdown.org/yihui/blogdown/)

]

.pull-right1[
<img src="data:image/png;base64,#images/blogdown_ex.png" width="100%" />
]

---
background-image: url(data:image/png;base64,#images/vitae.png)
background-size: 10%
background-position: 42% 2%

## Vitae
.pull-left1[

Resume's are important, updating them also important but at times tedious.
And finding nice templates for resumes is not easy.

Vitae is a great package to migrate your resume to Rmarkdown and create truly stunning resumes!

- Mitchell O'Hara-Wild's - [Vitae package for resumes](https://pkg.mitchelloharawild.com/vitae/)  
]

.pull-right1[
<img src="data:image/png;base64,#https://pbs.twimg.com/media/Dsqo7mdU0AALGEe?format=jpg&name=medium" width="100%" />
]

---

# More

+ [`redoc` 📦](https://noamross.github.io/redoc/)

+ [`spelling` 📦](https://docs.ropensci.org/spelling/)

+ [`wordcountaddin` 📦](https://github.com/benmarwick/wordcountaddin)

+ [`pkgdown` 📦](https://pkgdown.r-lib.org/)

+ [`officedown` 📦](https://davidgohel.github.io/officedown/)

---

# Take-aways

✔️ **Document your document:** use YAML to set up meaningful metadata

✔️ **Style your document:** use YAML to add options to your chosen output format

✔️ **Organize your text:** use markdown headers with `#`

✔️ **Organize your code:** use `knitr` chunk labels

✔️ **Style your text:** use markdown **bold**, _italics_, bullets, and lists

✔️ **Style your output:** use `knitr` chunk options

🧶 early, 🧶 often

---

## Extra tips!
**When naming code chunks, don't use `_` (underscore), but `-` (dash)**   
Some times when converting to pdf the underscore will cause issues

**When you get latex errors, start stripping down your document untill you find the problem part**

**Html is easier to render than pdf**  
because you dont need to go through latex...If you can "get away" with html reports do that!

**Customizing html reports is easier than pdf**

**Lists need _two_ spaces after each element**  
Rmarkdown and markdown will not create a line break (even if text is on different consecutive lines) unless there are _two_ spaces at the end of a line
  - double line break (i.e. consecutive lines have a blank line between them) usually creates a larger line space and is usually not what you are after, so remember the double space at the end

---
class: middle, center

# ⏱

# Lecture done!

### Next, take some time to familiarize yourself with the elements in `02-explore.Rmd`!